home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / source / gadlay17.lha / gadlayout.doc < prev    next >
Encoding:
Text File  |  1993-12-16  |  19.9 KB  |  418 lines
  1. TABLE OF CONTENTS
  2.  
  3. gadlayout/FreeLayoutGadgets
  4. gadlayout/GadgetArrayIndex
  5. gadlayout/GadgetKeyCmd
  6. gadlayout/GetGadgetInfo
  7. gadlayout/GL_SetGadgetAttrsA
  8. gadlayout/LayoutGadgetsA
  9. gadlayout/FreeLayoutGadgets                       gadlayout/FreeLayoutGadgets
  10.  
  11.    NAME
  12.        FreeLayoutGadgets -- Frees gadgets laid out with LayoutGadgets().
  13.  
  14.    SYNOPSIS
  15.        FreeLayoutGadgets(gad_info);
  16.        VOID FreeLayoutGadgets(APTR);
  17.  
  18.    FUNCTION
  19.        Frees all resources used in creating and laying out gadgets with
  20.        LayoutGadgets().  This frees all gadgets as well as other
  21.        resources used.  Generally this will be called after a call to
  22.        CloseWindow() in Intuition.
  23.  
  24.    INPUTS
  25.        gad_info - The pointer returned by LayoutGadgets().
  26.  
  27.    SEE ALSO
  28.        LayoutGadgetsA()
  29.  
  30. gadlayout/GadgetArrayIndex                         gadlayout/GadgetArrayIndex
  31.  
  32.    NAME
  33.        GadgetArrayIndex -- Get a gadget's index in the LayoutGadget array.
  34.  
  35.    SYNOPSIS
  36.        i = GadgetArrayIndex(gad_id, gadgets)
  37.        WORD GadgetArrayIndex(WORD, struct LayoutGadget *)
  38.  
  39.    FUNCTION
  40.        Given a gadget ID, returns the index of that gadget's definition
  41.        in the LayoutGadget array.  For example, in cases where you need
  42.        to know a gadget's Gadget structure (eg. if you wanted to use
  43.        the Intuition function ActivateGadget() to make a string or an
  44.        integer gadget active), you would need to lookup the lg_Gadget
  45.        field in the LayoutGadget array.  You MUST NOT GIVE THE ARRAY
  46.        INDEX YOURSELF, THIS IS NOT GUARUNTEED TO REMAIN VALID!  Instead,
  47.        pass the id of the gadget that you want and this function will
  48.        return the array index for you.
  49.  
  50.    INPUTS
  51.        gad_id - The ID of the gadget you want to find.
  52.        gadgets - The LayoutGadget array that this gadget is defined in.
  53.  
  54.    RESULT
  55.        i - The index into the LayoutGadget array of the entry of the
  56.           gadget ID you asked for.
  57.  
  58. gadlayout/GadgetKeyCmd                                 gadlayout/GadgetKeyCmd
  59.  
  60.    NAME
  61.        GadgetKeyCmd -- Returns the key equivalent of a gadget.
  62.  
  63.    SYNOPSIS
  64.        key = GadgetKeyCmd(gad_info, gad_id, gadgets)
  65.        UBYTE GadgetKeyCmd(APTR, WORD, struct LayoutGadget *)
  66.  
  67.    FUNCTION
  68.        Looks for an underscore (_) character in a gadgets label to determine
  69.        the key equivalent, if any, for a gadget.  This is particularly
  70.        useful in localized code where the key equivalent may differ
  71.        depending on what locale the user is running under.
  72.  
  73.    INPUTS
  74.        gad_info - The value returned by LayoutGadgetsA().
  75.        gad_id - The GadgetID of the gadget whose key equivalent you want.
  76.        gadgets - The LayoutGadget arrow that your gadget exists in.
  77.  
  78.    RESULT
  79.        key - The key equivalent for the gadget, always in lowercase.
  80.  
  81.    BUGS
  82.        Only works if GT_Underscore, '_' is used for key equivalents, will
  83.        not work if another underscore character is used.
  84.  
  85. gadlayout/GetGadgetInfo                               gadlayout/GetGadgetInfo
  86.  
  87.    NAME
  88.        GetGadgetInfo -- Get a pointer to a gadget's structure.
  89.  
  90.    SYNOPSIS
  91.        gadget = GetGadgetInfo(gad_id, gadgets)
  92.        WORD GetGadgetInfo(WORD, struct LayoutGadget *)
  93.  
  94.    FUNCTION
  95.        Given a gadget ID, returns the GadTools Gadget structure of that
  96.        gadget.
  97.  
  98.    INPUTS
  99.        gad_id - The ID of the gadget you want to find.
  100.        gadgets - The LayoutGadget array that this gadget is defined in.
  101.  
  102.    RESULT
  103.        gadget - The GadTools Gadget structure of the gadget ID you asked
  104.            for.  As per GadTools conventions, the actual contents of this
  105.            structure are PRIVATE.
  106.  
  107.    SEE ALSO
  108.        GadgetArrayIndex()
  109.  
  110. gadlayout/GL_SetGadgetAttrsA                     gadlayout/GL_SetGadgetAttrsA
  111.  
  112.    NAME
  113.        GL_SetGadgetAttrsA -- Change attributes of a GadLayout gadget.
  114.        GL_SetGadgetAttrs -- Varargs stub for GL_SetGadgetAttrsA.
  115.  
  116.    SYNOPSIS
  117.        GL_SetGadgetAttrsA(gad_info, gad, win, req, taglist)
  118.        VOID GL_SetGadgetAttrsA(APTR, struct Gadget *, struct Window *,
  119.                                struct Requester *, struct TagItem *)
  120.  
  121.        GL_SetGadgetAttrs(gad_info, gad, win, req, firsttag, ...)
  122.        VOID GL_SetGadgetAttrs(APTR, struct Gadget *, struct Window *,
  123.                               struct Requester *, Tag *, ...)
  124.  
  125.    FUNCTION
  126.        Changes attributes for one of the GadLayout gadget kinds according
  127.        according to the attributes chosen in the tag list.
  128.  
  129.    INPUTS
  130.        gad_info - The value returned by LayoutGadgetsA().
  131.        gad - Pointer to the gadget in question.
  132.        win - Pointer to the window containing the gadget.
  133.        req - Pointer to the requester containing the gadget, or NULL if
  134.            not in a requester. (Not implemented yet, use NULL.)
  135.        taglist - Pointer to a TagItem list.
  136.  
  137.    TAGS
  138.        IMAGEBUTTON_KIND:
  139.        GLIM_Image (struct Image *) - Changes the image displayed in the
  140.            gadget.
  141.        GLIM_Toggle (BOOL) - Makes the gadget a toggle switch gadget (if
  142.            it is not already) and puts it into either the selected state
  143.            (ti_Data = TRUE) or deselectd state (ti_Data = FALSE).
  144.  
  145.    BUGS
  146.        This function is not compatable with itself in releases 1.5 and
  147.        lower, because of the new pi parameter!  ALL OLD CODE WILL HAVE TO
  148.        BE CHANGED!!!
  149.  
  150.        Attributes not pertaining to a specific gadget kind will not
  151.        always be ignored, so you will need to be careful that you only
  152.        try to change attributes that are valid for the gadget's kind.
  153.  
  154. gadlayout/LayoutGadgetsA                             gadlayout/LayoutGadgetsA
  155.  
  156.    NAME
  157.        LayoutGadgetsA -- Formats an array of GadTools gadgets.
  158.        LayoutGadgets -- Varargs stub for LayoutGadgetsA().
  159.  
  160.    SYNOPSIS
  161.        gad_info = LayoutGadgetsA(gad_list, gadgets, screen, taglist)
  162.        APTR LayoutGadgetsA(struct Gadget **, struct LayoutGadget *,
  163.                            struct Screen *, struct TagItem *)
  164.  
  165.        gad_info = LayoutGadgets(gad_list, gadgets, screen, firsttag, ...)
  166.        APTR LayoutGadgets(struct Gadget **, struct LayoutGadget *,
  167.                           struct Screen *, Tag *, ...)
  168.  
  169.    FUNCTION
  170.        Creates a laid-out gadget list from a LayoutGadget array, which
  171.        describes each gadget you want to create.  Gadgets you create
  172.        can be any of the gadget kinds supported by GadTools, as well
  173.        as any of the extended gadget kinds provided by GadLayout.
  174.        Gadgets can easily be defined so that the automatically adjust
  175.        their sizes and positions to accomodate fonts of any size
  176.        (including proportional fonts) and also to adapt to different
  177.        locale strings.  The real power of GadLayout is that allows you
  178.        to create a gadget layout that dynamically adjusts to different
  179.        user's environments.
  180.  
  181.    INPUTS
  182.        gad_list - Pointer to the gadget list pointer, this will be
  183.            ready to pass to OpenWindowTags() or AddGList().
  184.  
  185.        gadgets - An array of LayoutGadget structures.  Each element
  186.            in the array describes one of the gadgets that you will
  187.            be creating.  Each LayoutGadget structure in the array
  188.            should be initialized as follows:
  189.  
  190.            lg_GadgetID - The ID for this gadget.
  191.            lg_LayoutTags - A taglist consisting of the following tags:
  192.                GL_GadgetKind (ULONG) - Which gadget kind to use.  This
  193.                    may be any of the GadTools gadget kinds (defined in
  194.                    libraries/gadtools.h), or one of the additional kinds
  195.                    provided by GadLayout, which are:
  196.                    IMAGEBUTTON_KIND : A button gadget with that uses an
  197.                                       Intuition Image structure for its
  198.                                       contents.  The image will be centred
  199.                                       automatically.
  200.                    DRAWER_KIND : A drawer button gadget.  Use this to
  201.                                  allow the user to use the ASL file
  202.                                  requester to select a path.
  203.                    FILE_KIND : A file button gadget.  Use this to allow
  204.                                the user to use the ASL file requester
  205.                                to select a file.
  206.                    Additional kinds may be added in the future.
  207.                GL_Width (WORD) - Absolute gadget width, in pixels.
  208.                GL_DupeWidth (UWORD) - Duplicate the width of another
  209.                    gadget.
  210.                GL_AutoWidth (WORD) - Set width according to length of
  211.                    text label + ti_Data.  Note that this function
  212.                    does not take into account the amount of space any
  213.                    gadget imagery might take within the gadgets area.
  214.                GL_Columns (UWORD) - Set width of gadget so that
  215.                    approximately ti_Data columns of text with the
  216.                    gadget's font will fit.  This will only be an
  217.                    approximation, because with proportional fonts the
  218.                    width of character varies.  Note that this function
  219.                    does not take into account the amount of space any
  220.                    gadget imagery might take within the gadgets area.
  221.                GL_AddWidth (WORD) - Add some value to the total width
  222.                    calculation.
  223.                GL_MinWidth (WORD) - Make sure that the final width of
  224.                    the gadget is at least this.
  225.                GL_MaxWidth (WORD) - Make sure that the final width of
  226.                    the gadget is at most this.
  227.                GL_Height (WORD) - Absolute gadget width.
  228.                GL_DupeHeight (UWORD) - Duplicate the height of another
  229.                    gadget.
  230.                GL_HeightFactor (UWORD) - Make the gadget height a multiple
  231.                    of the font height (useful for LISTVIEW_KIND gadgets).
  232.                GL_AutoHeight (WORD) - Set height according to height of
  233.                    text font + ti_Data.
  234.                GL_AddHeight (WORD) - Add some value to the total height
  235.                    calculation.
  236.                GL_MinHeight (WORD) - Make sure that the final height of
  237.                    the gadget is at least this.
  238.                GL_MaxHeight (WORD) - Make sure that the final height of
  239.                    the gadget is at most this.
  240.                GL_Top (WORD) - Absolute top edge.
  241.                GL_TopRel (UWORD)  - Top edge relative to bottom edge of
  242.                    another gadget (specified by its gadget ID).
  243.                GL_AdjustTop (WORD) - ADD the height of the text font +
  244.                    ti_Data to the top edge (often used to to properrly
  245.                    position gadgets that have their label above).
  246.                GL_AlignTop (UWORD) - Align the top edge of the gadget
  247.                    with the top edge of another gadget (specified by its
  248.                    gadget ID).
  249.                GL_AddTop (WORD) -  Add some value to the final top edge
  250.                    calculation.
  251.                GL_Bottom (WORD) - Absolute bottom edge.
  252.                GL_BottomRel (UWORD) - Bottom edge relative to top edge of
  253.                    another gadget (specified by its gadget ID).
  254.                GL_AlignBottom (UWORD) - Align the bottom edge of the gadget
  255.                    with the bottom edge of another gadget (specified by its
  256.                    gadget ID).
  257.                GL_AddBottom (WORD) - Add some value to the final bottom edge
  258.                    calculation.
  259.                GL_Left (WORD) - Absolute left edge.
  260.                GL_LeftRel (UWORD) - Left edge relative to right edge of
  261.                    another gadget (specified by its gadget ID).
  262.                GL_AdjustLeft (WORD) - ADD the width of the text label +
  263.                    ti_Data to the left edge.
  264.                GL_AlignLeft (UWORD) - Align the left edge of the gadget
  265.                    with the left edge of another gadget (specified by its
  266.                    gadget ID).
  267.                GL_AddLeft (WORD) - Add some value to the final left edge
  268.                    calculation.
  269.                GL_Right (WORD) - Absolute right edge.
  270.                GL_RightRel (UWORD) - Right edge relative to left edge of
  271.                    another gadget (specified by its gadget ID).
  272.                GL_AlignRight (UWORD) - Align the right edge of the gadget
  273.                    with the right edge of another gadget (specified by its
  274.                    gadget ID).
  275.                GL_AddRight (WORD) - Add some value to the final right edge
  276.                    calculation.
  277.                GL_GadgetText (STRPTR) - Gadget text label.
  278.                GL_TextAttr (struct TextAttr *) - Desired font for gadget
  279.                    label, will override the GL_DefTextAttr if used.
  280.                GL_Flags - (ULONG) Gadget flags.
  281.                GL_UserData (VOID *)- Gadget UserData.
  282.                GL_LocaleText - Gadget label taken from a locale catalog,
  283.                    you supply the locale string ID.  If you use this tag
  284.                    you MUST have used GL_AppStrings in your call to
  285.                    LayoutGadgets().
  286.  
  287.                If you've specified one of GadLayout's own gadget kinds
  288.                with GL_GadgetKind, the following tags are available for
  289.                defining attributes of those gadgets:
  290.  
  291.                GLIM_Image (struct Image *) - Provide a pointer to the
  292.                    Image structure to to be used in an IMAGEBUTTON_KIND
  293.                    structure.  This pointer only need be valid when
  294.                    LayoutGadgets() is called.
  295.                GLIM_ReadOnly (BOOL) - Specifies that the gadget is read-
  296.                    only.  It will get a recessed border and will not be
  297.                    highlighted when clicked on.
  298.                GLIM_Toggle (BOOL) - If true, the gadget becomes a toggle
  299.                    switch gadget that can be clicked on and off.  The
  300.                    initial state of the gadget will be unselected.
  301.  
  302.                Generally you need only specify the tags when the data
  303.                has changed from the previously gadget.  This gets a
  304.                little tricky when you use the relation tags like
  305.                GL_TopRel, as this means that gadgets will not be
  306.                processed in sequential order necessarily.
  307.  
  308.            lg_GadToolsTags - When defining a GadTools gadgets, you
  309.                can pass a GadTools taglist to set options for that
  310.                gadget.  This would be the same set of tags that you
  311.                might pass to CreateGadgetA() if you were using GadTools
  312.                directly.
  313.            lg_Gadget - The pointer to the Gadget structure created for
  314.                this gadget will be placed here.  You should initialize
  315.                this field to NULL.  WARNING: The gadget structure
  316.                created READ-ONLY!
  317.  
  318.        screen - A pointer to the screen that the gadgets will be
  319.            created for.  The is required so that the layout routines
  320.            can get display info about the screen, no rendering will
  321.            be done.
  322.  
  323.        taglist - Pointer to a TagItem list (see below for allowed tags)
  324.  
  325.    TAGS
  326.        GL_RightExtreme (LONG *) - A pointer to a LONG where GadLayout
  327.            will put the co-ordinate of the rightmost point where any
  328.            imagery of the laid-out gadgets will be drawn.  Use this to
  329.            open a window exactly big enough to hold all your gadgets.
  330.            Use this value alone with the WA_InnerWidth window tag and
  331.            NOT WA_Width, since you do not know how big the window
  332.            border will be.
  333.        GL_LowerExtreme (LONG *) - A pointer to a LONG where GadLayout
  334.            will put the co-ordinate of the lowermost point where any
  335.            imagery of the laid-out gadget will be drawn.  Use this to open
  336.            a window exactly big enough to hold all your gadgets.
  337.            Use this value alone with the WA_InnerHeight window tag and
  338.            NOT WA_Height, since you do not know how big the window
  339.            border will be.
  340.        GL_DefTextAttr (struct TextAttr *) - Instead of having to indicate
  341.            a TextAttr for each gadget, you can specify a font to be used
  342.            by default for all your gadgets.
  343.        GL_Catalog (struct Catalog *) - Specify the locale catalog to use
  344.            to get your strings from.  If you wish to localize your gadget
  345.            string via GL_LocaleText you MUST use this tag as well as
  346.            GL_AppStrings.  You must also make certain that locale.library
  347.            has been opened successfully with LocaleBase pointing to the
  348.            library base.
  349.        GL_AppStrings (struct AppString **) - If you wish to make your
  350.            gadgets localized, you you must pass a list of strings and
  351.            their IDs.  The format of these strings is an array of
  352.            structures, with a LONG that contains the ID and a STRPTR
  353.            pointing to the string, i.e.:
  354.                struct AppString
  355.                {
  356.                    LONG   as_ID;
  357.                    STRPTR as_Str;
  358.                };
  359.            These strings serve as the default language for the gadgets.
  360.            See locale.library documentation for more information on
  361.            localizing applications.  You MUST use this tag in addition to
  362.            GL_Catalog if you wish to use GL_LocaleText to localize your
  363.            gadgets.
  364.        GL_NoCreate (BOOL) - Set to TRUE if you don't want the layout
  365.            routine to actually create any gadgets.  This is used when
  366.            you want to use the GL_RightExtreme and GL_LowerExtreme tags
  367.            to find out how much space your gadgets will take, but don't
  368.            actually want to create the gadgets just yet.
  369.        GL_BorderTop (UWORD) - The size of the top border of your window.
  370.            If your window does not have the WFLG_GIMMEZEROZERO flag set,
  371.            it will be necessary to pass the size of the window borders.
  372.            This value can be gotten either from the Window structure of
  373.            your window (if it is already open), or from the Screen
  374.            structure of your screen (see intuition/screens.h for details
  375.            about this).  NOTE: This value is NOT added to the value
  376.            returned by GL_LowerExtreme!
  377.        GL_BorderLeft (UWORD) - The size of the left border of your window.
  378.            If your window does not have the WFLG_GIMMEZEROZERO flag set,
  379.            it will be necessary to pass the size of the window borders.
  380.            This value can be gotten either from the Window structure of
  381.            your window (if it is already open), or from the Screen
  382.            structure of your screen (see intuition/screens.h for details
  383.            about this).  NOTE: This value is NOT added to the value
  384.            returned by GL_RightExtreme.
  385.  
  386.    RESULT
  387.        gad_info - A pointer to a private structure.  You must keep this
  388.            value and pass it to FreeLayoutGadgets() later on in order to
  389.            free up all resources used by your gadgets.
  390.  
  391.    NOTES
  392.        You must be careful with the taglist in the lg_LayoutTags field.
  393.        Tags are processed sequentally in the order you give them in, and
  394.        if a tag references another gadget (eg. the GL_TopRel tag), then
  395.        processing of the current gadget halts while the referenced gadget
  396.        is processed (if it has not already been processed).  Problems can
  397.        arise if this gadget refers back to the original gadget that
  398.        referenced it, if it is referring to a field that has not yet been
  399.        processed in that gadget.  For example, gadget GAD_BUTTON1 may use
  400.        the GL_TopRel tag to refer to GAD_BUTTON2, which may subsequently
  401.        make use of GL_LeftRel to refer back to GAD_BUTTON1.  The gadgets
  402.        left edge must already be defined in GAD_BUTTON1 (i.e. a tag such
  403.        as GL_Left MUST appear before the GL_TopRel tag) if GAD_BUTTON2 is
  404.        to get the left edge desired.
  405.  
  406.    BUGS
  407.        Doesn't do any checking to make sure gadgets don't overlap.
  408.        Essentially assumes you know what you're doing with the layout.
  409.  
  410.        Bad things will happen if you provide an IMAGEBUTTON_KIND gadget
  411.        with an image too big to fit within the dimensions you've provided
  412.        for the gadget.
  413.  
  414.    SEE ALSO
  415.        FreeLayoutGadgets(), gadlayout/gadlayout.h, libraries/gadtools.h,
  416.        GadTools documentation.
  417.  
  418.